Deploy docs site with Hugo via GitHub Actions by oschwald · Pull Request #628 · maxmind/minfraud-api-java

oschwald · 2026-05-15T22:43:00Z

Summary

Migrates the Pages index from Jekyll on gh-pages to a Hugo build that
publishes back onto gh-pages from GitHub Actions. All CSS is now
inlined in the layout template — no external CDN dependencies.

Hugo site lives under docs/ on main and mounts README.md as the
home page
A small pill nav links from the overview to the Javadoc at
/doc/latest/
.github/workflows/pages.yml builds with mise run build-docs and
pushes to gh-pages via peaceiris/actions-gh-pages with
keep_files: true, so every /doc/vX.Y.Z/ Javadoc subtree stays
untouched
dev-bin/release.sh no longer regenerates the Jekyll index.md;
the Javadoc-publishing block is unchanged

Same design as MaxMind-DB PR #221.

For STF-448.

Post-merge steps

Verify the live site at https://maxmind.github.io/minfraud-api-java/
and a sample /doc/latest/ still loads after the next workflow run
In a separate commit on gh-pages, drop the legacy Jekyll source
files

Pages source stays on gh-pages — no Terraform change for this repo.

Test plan

mise run build-docs succeeds with no warnings
Rendered <title>, <h1>, and pill nav are correct
No static-gh.maxmind.com references in the new site
Build job passes in CI (push step only runs on main)
After merge, confirm the workflow pushes successfully to gh-pages
and /doc/vX.Y.Z/ subtrees are preserved

🤖 Generated with Claude Code

gemini-code-assist

Code Review

This pull request migrates the project's documentation system to Hugo, replacing the manual generation logic in the release script. It introduces a new Hugo configuration that mounts the project README as the main content, along with custom layouts and CSS. Additionally, mise configuration is updated to include Hugo and new tasks for building and serving the documentation site. The review feedback suggests enhancing the HTML template by dynamically setting the language attribute and making the API documentation link configurable via the site settings.

gemini-code-assist · 2026-05-15T22:47:40Z

@@ -0,0 +1,207 @@
+<!doctype html>
+<html lang="en">


The lang attribute is hardcoded to "en". While appropriate for the current content, it is better practice to use the site's configured language to support future internationalization.

Suggested change

<html lang="en">

<html lang="{{ .Site.Language.LanguageCode | default "en" }}">

gemini-code-assist · 2026-05-15T22:47:40Z

+  <body>
+    <nav class="page-nav">
+      <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active"{{ end }}>Overview</a>
+      <a href="{{ "doc/latest/" | relURL }}">API documentation</a>


The link to the API documentation is hardcoded to doc/latest/. If the Javadoc directory structure changes or if you want to link to a specific version, this will need manual updates. Consider if this should be a configurable parameter in hugo.toml.

oschwald · 2026-05-18T17:06:05Z

/gemini review

gemini-code-assist

Code Review

This pull request migrates the documentation system from a manual script-based approach to a Hugo static site generator. Key changes include the addition of Hugo configuration and layouts in the docs/ directory, updates to the .gitignore and mise development environment to support Hugo, and the removal of legacy documentation generation logic from the release script. As there were no review comments provided, I have no further feedback.

Build with `mise run build-docs`, preview with `mise run serve-docs`. The site mounts the existing `README.md` as the home page so the source of truth stays in one place. A small pill nav links from Overview to the versioned API documentation that lives on the `gh-pages` branch under `doc/latest/`. CSS is inlined in the layout template — no external dependencies. Same Charter serif + forest-green design as the MaxMind-DB spec site. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Deploys the Hugo docs site on push to main. The workflow builds the site with `mise run build-docs` and pushes the rendered output onto the existing `gh-pages` branch with `keep_files: true` — that preserves every `/doc/vX.Y.Z/` Javadoc subtree exactly as the release script publishes them. Pages keeps deploying from `gh-pages`, so no Terraform change is needed for this repo. All actions are SHA-pinned. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Hugo on `main` now owns the Pages index, so the release script no longer needs to write a Jekyll front-matter wrapper around README.md on the gh-pages branch. The Javadoc-publishing block that creates `doc/$tag/` and updates the `doc/latest` symlink is unchanged — that versioned tree continues to live on gh-pages and is preserved by the new workflow's `keep_files: true`. For STF-448. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

horgh · 2026-05-20T02:26:39Z

+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/public
+          publish_branch: gh-pages
+          keep_files: true


From Claude, not sure:

- Stale Jekyll artifacts will linger on gh-pages. Existing branch contains _config.yml, _layouts/default.html, stylesheets/pygments.css, old index.md. With keep_files: true, none will be removed. peaceiris writes .nojekyll so they're inert, but still accessible as raw files. One-time manual cleanup recommended.

Same as on the GeoIP2-java and MaxMind-DB-Reader-java PRs: deferred to post-merge, captured on the Linear STF-448 cleanup checklist. The cleanup runs once after the Hugo workflow has populated each gh-pages with new content so the site isn't briefly empty.

(Claude, responding on behalf of @oschwald.)

horgh · 2026-05-20T02:27:26Z

+  <body>
+    <nav class="page-nav">
+      <a href="{{ .Site.Home.RelPermalink }}"{{ if .IsHome }} class="active" aria-current="page"{{ end }}>Overview</a>
+      <a href="{{ "doc/latest/" | relURL }}">API documentation</a>


From Claude, seems right:

- README still references "API tab" (lines 38-39); new nav labels it "API documentation".

Addressed in 8d07870 — README.md line 39 now reads "and follow the 'API documentation' link" instead of "under the API tab". Matches the new Hugo pill nav label.

(Claude, responding on behalf of @oschwald.)

horgh · 2026-05-20T02:28:38Z

+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: true


From Claude, not sure:

- pages.yml:22 uses persist-credentials: true unnecessarily — inconsistent with rest of repo, peaceiris uses its own token. Set to false.

Addressed in 084cb12 — persist-credentials: false on the checkout. Matches the pattern in the rest of this repo's workflows.

(Claude, responding on behalf of @oschwald.)

`disableKinds = ["taxonomy"]` only disables the taxonomy list page; post-Hugo-0.73 individual term pages are a separate kind. The site declares no taxonomies, so neither list nor term pages have content, but the config now matches its stated intent. Disabling RSS also suppresses an empty `index.xml` that nothing subscribes to. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Hugo's built-in fallback renders an empty `<main></main>` for the 404 page. Provide a minimal "Page not found" body with a link back to the site home, reusing the Charter/forest-green design tokens from the main layout. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

oschwald · 2026-05-20T15:16:06Z

/gemini review

gemini-code-assist

Code Review

This pull request transitions the project's documentation from a manual README-based setup to a Hugo-powered static site. Changes include adding Hugo configuration, layout templates, and integrating Hugo into the mise environment with dedicated build and serve tasks. The release script was also updated to remove legacy documentation generation. A review comment correctly identifies that the baseURL is missing in the Hugo configuration, which is essential for proper link resolution when hosted on GitHub Pages.

gemini-code-assist · 2026-05-20T15:17:36Z

@@ -0,0 +1,13 @@
+title = "MaxMind minFraud Java API"


The baseURL configuration is missing. For GitHub Pages project sites hosted in a subdirectory (e.g., /minfraud-api-java/), Hugo requires baseURL to correctly generate links. Without it, .Site.Home.RelPermalink (used in the 404 page and navigation) will point to the domain root (/) instead of the project root, leading to broken links when the site is accessed from a subpath or a 404 error page.

Suggested change

title = "MaxMind minFraud Java API"

baseURL = "https://maxmind.github.io/minfraud-api-java/"

title = "MaxMind minFraud Java API"

baseURL was deliberately removed from hugo.toml in an earlier round of this PR. It's now passed via the HUGO_BASEURL env var in the workflow's "Build docs" step, which Hugo natively supports as a config override. The deployed link generation is correct.

(Claude, responding on behalf of @oschwald.)

`.File` is nil on virtual pages (e.g., taxonomy listings before they were disabled). Wrap with `with .File` so the title rendering is null-safe even if future virtual pages get enabled. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

peaceiris/actions-gh-pages uses its own `github_token` input for the push to gh-pages; the credentials persisted by `actions/checkout` aren't read. Setting `persist-credentials: false` matches the rest of the workflows in this repo and silences zizmor's `artipacked` rule. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The README still pointed at the old Jekyll site's "API tab" nav label. The new Hugo pill nav uses the "API documentation" label, so update the README to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

oschwald · 2026-05-20T16:54:38Z

/gemini review

gemini-code-assist

Code Review

This pull request migrates the project's documentation to a Hugo-based site, adding necessary configuration files, CSS, and HTML templates while updating the release script and mise environment. The reviewer identified a critical missing baseURL in the Hugo configuration that would break links on GitHub Pages and suggested inlining CSS within the templates to align with the PR's stated goals and improve performance.

gemini-code-assist · 2026-05-20T16:56:37Z

@@ -0,0 +1,13 @@
+title = "MaxMind minFraud Java API"


The baseURL is missing from the Hugo configuration. For GitHub Pages project sites (like https://maxmind.github.io/minfraud-api-java/), Hugo needs the baseURL to correctly resolve relative links and asset paths. Without it, links generated via relURL or RelPermalink will point to the root of the domain instead of the project subpath, leading to broken styles and navigation on the live site.

Suggested change

title = "MaxMind minFraud Java API"

baseURL = "https://maxmind.github.io/minfraud-api-java/"

title = "MaxMind minFraud Java API"

baseURL was deliberately removed from hugo.toml in an earlier round of this PR. It's passed via the HUGO_BASEURL env var in the workflow's "Build docs" step (Hugo natively respects this as a config override). The deployed link generation is correct.

(Claude, responding on behalf of @oschwald.)

gemini-code-assist · 2026-05-20T16:56:37Z

+    {{- $css := resources.Get "css/main.css" -}}
+    <link rel="stylesheet" href="{{ $css.RelPermalink }}" />


The PR description mentions that all CSS is inlined in the layout template to avoid external dependencies, but the current implementation uses a <link> tag. Inlining the CSS directly into the <head> would match the stated goal and slightly improve performance by saving an HTTP request.

Suggested change

{{- $css := resources.Get "css/main.css" -}}

<link rel="stylesheet" href="{{ $css.RelPermalink }}" />

{{- $css := resources.Get "css/main.css" | minify -}}

<style>{{ $css.Content | safeCSS }}</style>

The PR description is stale — externalizing the CSS in round 9 was a deliberate choice on top of the earlier inlined form, made to enable browser caching of the stylesheet across pages on the docs site. The code is doing what we want; we'll update the PR description to reflect the current state.

(Claude, responding on behalf of @oschwald.)

gemini-code-assist · 2026-05-20T16:56:37Z

+    {{- $css := resources.Get "css/main.css" -}}
+    <link rel="stylesheet" href="{{ $css.RelPermalink }}" />


Similar to the default layout, the CSS here is linked rather than inlined as described in the PR summary. Inlining it here ensures the 404 page remains styled even if there are issues resolving asset paths.

Suggested change

{{- $css := resources.Get "css/main.css" -}}

<link rel="stylesheet" href="{{ $css.RelPermalink }}" />

{{- $css := resources.Get "css/main.css" | minify -}}

<style>{{ $css.Content | safeCSS }}</style>

The PR description is stale — externalizing the CSS in round 9 was a deliberate choice on top of the earlier inlined form, made to enable browser caching of the stylesheet across pages on the docs site. The code is doing what we want; we'll update the PR description to reflect the current state.

(Claude, responding on behalf of @oschwald.)

Extracts the inline `<style>` block from the default and 404 layouts into `docs/assets/css/main.css`, served via Hugo's asset pipeline. Both layouts now reference the file via `<link rel="stylesheet">`, so the 404 page inherits the full stylesheet instead of duplicating a subset of rules. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

gemini-code-assist Bot reviewed May 15, 2026

View reviewed changes

gemini-code-assist Bot reviewed May 18, 2026

View reviewed changes

oschwald and others added 3 commits May 18, 2026 23:24

oschwald force-pushed the greg/stf-448 branch from cd89c65 to 9e15cfb Compare May 18, 2026 23:24

horgh requested changes May 20, 2026

View reviewed changes

oschwald and others added 2 commits May 20, 2026 14:29

oschwald force-pushed the greg/stf-448 branch from 8d07870 to 89d1568 Compare May 20, 2026 14:56

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

oschwald and others added 3 commits May 20, 2026 16:10

Update README API documentation reference

a92c533

The README still pointed at the old Jekyll site's "API tab" nav label. The new Hugo pill nav uses the "API documentation" label, so update the README to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

oschwald force-pushed the greg/stf-448 branch from 89d1568 to 0b1fba7 Compare May 20, 2026 16:10

gemini-code-assist Bot reviewed May 20, 2026

View reviewed changes

oschwald force-pushed the greg/stf-448 branch from 0b1fba7 to 278b689 Compare May 20, 2026 17:17

horgh approved these changes May 21, 2026

View reviewed changes

horgh merged commit 62dc1c1 into main May 21, 2026
27 checks passed

horgh deleted the greg/stf-448 branch May 21, 2026 02:21

	<html lang="en">
	<html lang="{{ .Site.Language.LanguageCode \| default "en" }}">

	title = "MaxMind minFraud Java API"
	baseURL = "https://maxmind.github.io/minfraud-api-java/"
	title = "MaxMind minFraud Java API"

		{{- $css := resources.Get "css/main.css" -}}
		<link rel="stylesheet" href="{{ $css.RelPermalink }}" />

Conversation

oschwald commented May 15, 2026

Summary

Post-merge steps

Test plan

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 15, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 15, 2026

Choose a reason for hiding this comment

Uh oh!

oschwald commented May 18, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oschwald commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oschwald commented May 20, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants